---
section: Backgrounds
title: Background Size
slug: /docs/background-size/
---

# Background Size

Utilities for controlling the background size of an element's background image.

<carbon-ad />

| React props             | CSS Properties             |
| ----------------------- | -------------------------- |
| `backgroundSize={size}` | `background-size: {size};` |

## Auto

Use `backgroundSize="auto"` to display the background image at its default size.

```jsx preview color=amber
<>
  <template preview>
    <x.div
      bg="amber-300"
      h={48}
      backgroundSize="auto"
      backgroundRepeat="no-repeat"
      backgroundPosition="center"
      backgroundImage="url('https://images.unsplash.com/photo-1490079027102-cd08f2308c73?ixlib=rb-1.2.1&ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&auto=format&fit=crop&w=200&h=200&q=80');"
    />
  </template>
  <x.div
    backgroundSize="auto"
    backgroundRepeat="no-repeat"
    backgroundPosition="center"
    backgroundImage="url(...)"
  />
</>
```

## Cover

Use `backgroundSize="cover"` to scale the background image until it fills the background layer.

```jsx preview color=light-blue
<>
  <template preview>
    <x.div
      bg="light-blue-300"
      h={48}
      backgroundSize="cover"
      backgroundRepeat="no-repeat"
      backgroundPosition="center"
      backgroundImage="url('https://images.unsplash.com/photo-1490079027102-cd08f2308c73?ixlib=rb-1.2.1&ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&auto=format&fit=crop&w=200&h=200&q=80');"
    />
  </template>
  <x.div
    backgroundSize="cover"
    backgroundRepeat="no-repeat"
    backgroundPosition="center"
    backgroundImage="url(...)"
  />
</>
```

## Contain

Use `backgroundSize="contain"` to scale the background image to the outer edges without cropping or stretching.

```jsx preview color=emerald
<>
  <template preview>
    <x.div
      bg="emerald-300"
      h={48}
      backgroundSize="contain"
      backgroundRepeat="no-repeat"
      backgroundPosition="center"
      backgroundImage="url('https://images.unsplash.com/photo-1490079027102-cd08f2308c73?ixlib=rb-1.2.1&ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&auto=format&fit=crop&w=200&h=200&q=80');"
    />
  </template>
  <x.div
    backgroundSize="contain"
    backgroundRepeat="no-repeat"
    backgroundPosition="center"
    backgroundImage="url(...)"
  />
</>
```

## Responsive

To control the size of an element's background image at a specific breakpoint, use responsive object notation. For example, adding the property `backgroundSize={{ md: "cover" }}` to an element would apply the `backgroundSize="cover"` utility at medium screen sizes and above.

```jsx
<x.div backgroundSize={{ md: 'cover' }} />
```

For more information about xstyled's responsive design features, check out [Responsive Design](/docs/responsive-design/) documentation.
